This document details the Atlas of Living Australia style guide for creating html files from R Markdown
A test of a chunk
library(kableExtra)
library(tidyverse)
# a table
head(mtcars, n=5) %>%
kbl() %>%
kable_styling()
| mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160 | 110 | 3.90 | 2.620 | 16.46 | 0 | 1 | 4 | 4 |
| Mazda RX4 Wag | 21.0 | 6 | 160 | 110 | 3.90 | 2.875 | 17.02 | 0 | 1 | 4 | 4 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 | 2.320 | 18.61 | 1 | 1 | 4 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 | 3.215 | 19.44 | 1 | 0 | 3 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 | 3.440 | 17.02 | 0 | 0 | 3 | 2 |
Create a new R Markdown document by selecting File –> New File –> R Markdown
In the left window menu, select New Template. Then select the ALA Template
In the top 3 lines, add your document title, your name and the date. Leave the remainder of the .yaml options unchanged.
Next, scroll down to the code chunk named upper right bio. This code chunk adds your image and links to your personal websites
`{r upper right bio, echo = FALSE}
htmltools::withTags(
div(id = "pictureposition",
# Save your own picture as "picture.jpg" to local directory
img(src = knitr::image_uri("picture.jpg"),
class = "clipped",
style = 'height:100px'),
# Add links to personal accounts below and uncomment
div(id = "linkposition",
# a(href="your-url", # twitter
# class="fab fa-twitter",
# style = "text-align:center"),
# a(href="your-url", # github
# class="fab fa-github",
# style = "text-align:center")
# a(href="your-url", # linkedIn
# class="fab fa-linkedin",
# style = "text-align:center")
)))
`
Click the Knit button in the upper menu (below file tabs, above script) to create an HTML file. A preview of your knitted HTML document can be viewed in the right pane. Code must run successfully from start to finish for a file to be Knit.
In the R Studio viewer pane, click the “Show in New Window ” button to view the page in your browser.
Using setwd() to set a working directory can create issues for folder paths. They often are a cause of issues when making reproducible workflows.
Instead, use the here() function from the here package to build the path where you read and write files. here() automatically creates paths relative to the top level directory.
Read a full description of how to use the here() function to create safe paths in Chapter 3 of What They Forgot to Teach You About R
For example:
library(ggplot2)
library(here)
df <- read.delim(here("projects", , "style_guide", "data.csv"))
p <- ggplot(df, aes(x, y)) + geom_point()
ggsave(here("plots", "foofy_scatterplot.png"))
To set the project root path according to your current code file:
here::i_am("style_guide.rmd")
In writing, we use sentences and paragraphs of varying lengths to build a flowing, logical story or argument. In the same way, code chunks can be used to structure lines of code to build a flowing, logical analysis or plot.
Code chunks should be brief. They should also offer notes or visual output that provides context to any transformations or outputs. Users should be able to follow each transformation that is made to your data, each output that results from a transformation, and any final output.
There is no single correct code chunk size - you must use your best judgement. If it seems that the result of one or several lines of code is unclear a potential reader, you may need to split the code chunks to make the results easier to follow.
For others to understand what your code does and why you made the choices you did, it is helpful to include brief summaries or your logic or what each line of your code does. It is also good to provide a brief interpretation of model output
stylerUse the styler package to ensure your code is formatted correctly and/or consistently, The styler package formats your code according to the tidyverse style guide (or another custome style) prior to uploading a finished file document.
See the styler github and tidyverse pages for more information
Install the styler package to add style buttons to your R Markdown Addins dropdown menu. Clicking Addins -> style active file will reformat the code in your active file. Clicking ** Addins** -> style active section will reformat code in your current section.
Alternatively, you style_file() or style_text() can be run in the console.
See the R Markdown cheat sheet for more information on R Markdown formatting
For tips to make your R Markdown output pretty, see Pimp my RMD by Yan Holtz
Several packages can create tables with nice formatting.
One example is kableExtra:
library(kableExtra)
kable(
head(mtcars, n=5)) %>% kable_styling()
| mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160 | 110 | 3.90 | 2.620 | 16.46 | 0 | 1 | 4 | 4 |
| Mazda RX4 Wag | 21.0 | 6 | 160 | 110 | 3.90 | 2.875 | 17.02 | 0 | 1 | 4 | 4 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 | 2.320 | 18.61 | 1 | 1 | 4 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 | 3.215 | 19.44 | 1 | 0 | 3 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 | 3.440 | 17.02 | 0 | 0 | 3 | 2 |
kableExtra is also able to be used using magittr or base piping:
mtcars %>%
group_by(gear) %>%
summarise(cyl = mean(cyl),
disp = mean(disp)) %>%
kbl() %>%
kable_styling()
| gear | cyl | disp |
|---|---|---|
| 3 | 7.466667 | 326.3000 |
| 4 | 4.666667 | 123.0167 |
| 5 | 6.000000 | 202.4800 |
head(mtcars |>
subset(select = c("cyl", "disp", "gear")), n = 5) |>
kbl() |>
kable_styling()
Controlling the size of figures can help when you want people to focus on trends of many plots or on details of a single plot.
You can control how many columns your plots created in a chunk are printed into.
Add out.width = c("50%", "50%"), fig.show = "hold":
``{r out.width=c('50%', '50%'), fig.show='hold'}
boxplot(1:10)
plot(rnorm(10))
`
Control other parts of figure output in the chunk header as well. For example:
``{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure: Here is a really important caption."}
library(tidyverse)
mpg %>%
ggplot( aes(x=reorder(class, hwy), y=hwy, fill=class)) +
geom_boxplot() +
xlab("class") +
theme(legend.position="none")
Figure: Here is a really important caption.
Run a model and want to show output? Use the model_parameters() function from the parameters package to make your output clear and organised. The model_parameters() function can be considered as a lightweight alternative to broom::tidy():
library(parameters)
model <- lm(Sepal.Width ~ Petal.Length * Species + Petal.Width, data = iris)
# regular model parameters
model_parameters(model)
## Parameter | Coefficient | SE | 95% CI | t(143) | p
## -------------------------------------------------------------------------------------------
## (Intercept) | 2.89 | 0.36 | [ 2.18, 3.60] | 8.01 | < .001
## Petal.Length | 0.26 | 0.25 | [-0.22, 0.75] | 1.07 | 0.287
## Species [versicolor] | -1.66 | 0.53 | [-2.71, -0.62] | -3.14 | 0.002
## Species [virginica] | -1.92 | 0.59 | [-3.08, -0.76] | -3.28 | 0.001
## Petal.Width | 0.62 | 0.14 | [ 0.34, 0.89] | 4.41 | < .001
## Petal.Length * Species [versicolor] | -0.09 | 0.26 | [-0.61, 0.42] | -0.36 | 0.721
## Petal.Length * Species [virginica] | -0.13 | 0.26 | [-0.64, 0.38] | -0.50 | 0.618
model_parameters() can also be used for parameter standardization:
# standardized parameters
model_parameters(model, standardize = "refit")
## Package 'effectsize' required to calculate standardized coefficients. Please install it.
## Parameter | Coefficient | SE | 95% CI | t(143) | p
## -------------------------------------------------------------------------------------------
## (Intercept) | 2.89 | 0.36 | [ 2.18, 3.60] | 8.01 | < .001
## Petal.Length | 0.26 | 0.25 | [-0.22, 0.75] | 1.07 | 0.287
## Species [versicolor] | -1.66 | 0.53 | [-2.71, -0.62] | -3.14 | 0.002
## Species [virginica] | -1.92 | 0.59 | [-3.08, -0.76] | -3.28 | 0.001
## Petal.Width | 0.62 | 0.14 | [ 0.34, 0.89] | 4.41 | < .001
## Petal.Length * Species [versicolor] | -0.09 | 0.26 | [-0.61, 0.42] | -0.36 | 0.721
## Petal.Length * Species [virginica] | -0.13 | 0.26 | [-0.64, 0.38] | -0.50 | 0.618
See the R markdown documentation to view chunk options.
echo and evalReaders should be able to identify where every file in a workflow comes from (little is more frustrating than wondering where a required data file is located). Code used to load or extract data (from galah, for example) should be clearly identified.
However, some code takes a very long time to run and you may have saved it locally or in a repository to save time and/or space. In this case, it is possible to show code without running it.
Add eval = FALSE to the chunk header to display the code but prevent the chunk from running:
``{r, eval = FALSE}
ala_counts(group_by = "phylum")
`
You can then load a local file in the background, without showing the code.
Add echo = FALSE to your chunk header to run the code but prevent the chunk from displaying:
``{r, echo = FALSE}
data <- readRDS(file = "local_file.rds")
`